Update dotnet sln #15694

Forgind · 2019-11-05T00:33:56Z

Reordered slightly and changed wording to make dotnet sln clearer. Added an example of dotnet sln list.

Change order and some wording and add an example.

dsplaisted

I think this line (which you didn't change) might not be correct:

dotnet sln [<SOLUTION_FILE>] add [--in-root] [-s|--solution-folder] <PROJECT_PATH>

I think there should be an argument going along with --solution-folder, ie:

dotnet sln [<SOLUTION_FILE>] add [--in-root] [-s|--solution-folder <SOLUTION_FOLDER>] <PROJECT_PATH>

dsplaisted · 2019-11-05T17:27:22Z

docs/core/tools/dotnet-sln.md

 ## Name

-`dotnet sln` - Modifies a .NET Core solution file.
+`dotnet sln` - Options for the projects in a .NET Core solution file.


I think the previous wording was actually better here.

Modifies wouldn't include list. Perhaps Options for listing or modifying the projects in?

Wondering if we should break this down into multiple pages like we did with dotnet tool

docs/core/tools/dotnet-sln.md

On standard syntax

mairaw

Thanks @Forgind. Left a couple of comments. Another option would be break the sln command page into one for each command like we have for other CLI commands, if that would be preferable as well.

mairaw · 2019-11-07T21:26:21Z

docs/core/tools/dotnet-sln.md


 #### Synopsis

 ```dotnetcli
-dotnet sln [<SOLUTION_FILE>] add [--in-root] [-s|--solution-folder] <PROJECT_PATH>
+dotnet sln [<SOLUTION_FILE>] add [--in-root] [-s|--solution-folder <SOLUTION_FOLDER>] <PROJECT_PATH> [<PROJECT_PATH>...]


We don't usually show the argument in the synopsis. Instead, we add that where the option is shown.

Suggested change

dotnet sln [<SOLUTION_FILE>] add [--in-root] [-s|--solution-folder <SOLUTION_FOLDER>] <PROJECT_PATH> [<PROJECT_PATH>...]

dotnet sln [<SOLUTION_FILE>] add [--in-root] [-s|--solution-folder] <PROJECT_PATH> [<PROJECT_PATH>...]

I just saw another PR where a customer was trying to add the same info. Do you two think that we should do that across the board? I closed the PR for now so we could discuss that.

If switches are well-named (as in --solution-folder), I don't think it's necessary, but if -s were the only way to express that, it would be better to include <SOLUTION_FOLDER>. Since consistency is good, I would say that if there is one case in which we can't have a well-named switch, we should do it across the board. Otherwise, it's fine to take it out.

I'll take it out for now.

To me it makes sense to show the argument in the synopsis in all cases. Otherwise you can't tell the difference between a switch like --in-root which doesn't accept an argument and one like --solution-folder which requires one.

mairaw · 2019-11-07T21:27:19Z

docs/core/tools/dotnet-sln.md

 dotnet sln add [-h|--help]
 ```

 #### Arguments

 - **`SOLUTION_FILE`**

-  The solution file to use. If not specified, the command searches the current directory for one. If there are multiple solution files in the directory, one must be specified.
+  The solution file to use. The command searches the current directory for one if it's left unspecified, failing if there are multiple solution files.


It's part of our style guide to start the sentence with the condition first.

mairaw · 2019-11-07T21:28:53Z

docs/core/tools/dotnet-sln.md


 #### Options

 - **`-h|--help`**

-  Prints out a short help for the command.
+  Prints out a short list of options for the command.


this is description for all --help options across CLI docs. If this is preferred version, we'd have to change across all docs.

mairaw · 2019-11-07T21:29:22Z

docs/core/tools/dotnet-sln.md

 dotnet sln [<SOLUTION_FILE>] remove [-h|--help]
 ```

 #### Arguments

 - **`SOLUTION_FILE`**

-  The solution file to use. If not specified, the command searches the current directory for one. If there are multiple solution files in the directory, one must be specified.
+  The solution file to use. The command searches the current directory for one if it's left unspecified, failing if there are multiple solution files.


again, starting with the condition is part of our style and voice

mairaw · 2019-11-07T21:29:51Z

docs/core/tools/dotnet-sln.md

-  Prints out a short help for the command.
-
-### `list`
+  Prints out configurable options for the command.


This looks different from the previous description for help.

I included two versions to see which you like better, but I don't like the current one. It's bad style to include a word in its definition, and this usage for "help" is awkward in English in my opinion, so I would prefer to use one of my versions. Do you like either?

Would we change in the CLI too? It's not exactly the same but it says help too.

I don't think that --help is only about options so I think both changes are a bit misleading.

I would.

That's true. How about one of:
"Emits a description of how to use dotnet sln list"
"Prints out a description of how to use dotnet sln list"
"Describes how to use dotnet sln list"
possibly replacing "dotnet sln list" with "this command"?

I vote for "Prints out a description of how to use the command." Whatever we end up with here we can propagate to the other CLI docs later.

mairaw · 2019-11-07T21:32:08Z

docs/core/tools/dotnet-sln.md


 #### Options

 - **`-h|--help`**

-  Prints out a short help for the command.
+  Prints out a short list of options for the command.

 - **`--in-root`**



line 100 would be the place to add the option argument for -s

I'm not following. -s is on line 100.

mairaw · 2019-11-07T21:38:28Z

Also, since we're looking at dotnet sln, I'd like to address my comment from #15522 (comment)

I don't really understand the new options for 3.0.

Also added a closes keyword at the PR description to close the related issue.

Forgind · 2019-11-07T22:14:37Z

I don't know what the new options for 3.0 are, and when I asked @dsplaisted about what I should make sure to include that isn't already there, he said there might not be anything to update. Where did you see that there are new options for dotnet sln in 3.0?

mairaw · 2019-11-10T00:02:07Z

I saw with dotnet sln add --help that there were two new options that I've already added previously:
https://review.docs.microsoft.com/en-us/dotnet/core/tools/dotnet-sln?branch=pr-en-us-15694#options-2

--in-root and -s|--solution-folder. But if all dotnet sln add is doing is adding existing projects to an existing solution, I don't really understand their intention.

Forgind · 2019-11-12T01:09:13Z

My understanding is that when you use dotnet sln add, it also creates obj, a folder with some information related to nuget, debugging, and so on. If you use --in-root, it doesn't make that folder; if you use -s, it lets you specify where you want the folder to be created. Is that correct, @dsplaisted? Also, that explanation was based on my reading of what --help printed out, but it seemed like --in-root did the opposite—making a folder where there otherwise wouldn't be one. Is that expected behavior?

dsplaisted · 2019-11-12T02:40:50Z

@Forgind No, dotnet sln add shouldn't create an obj folder. Building a project will typically create a bin folder for the output and an obj folder for the intermediate files, but that's not related to the solution.

A solution can have folders to organize the projects in the solution. Those folders don't necessarily need to match the folders the projects are in on disk. It sounds like dotnet sln add will by default create solution folders matching the folders on disk, but you can override the solution folders with -s, or tell it not to create any with --in-root.

mairaw · 2020-01-14T03:13:47Z

Resolved merge conflicts

mairaw · 2020-02-20T00:46:33Z

Resolved merge conflicts

changes made since last review

tdykstra

I made a couple of suggestions for you to consider.

docs/core/tools/dotnet-sln.md

tdykstra · 2020-02-20T16:33:01Z

docs/core/tools/dotnet-sln.md

@@ -31,42 +31,64 @@ dotnet new sln

 - **`SOLUTION_FILE`**

-  The solution file to use. If not specified, the command searches the current directory for one. If there are multiple solution files in the directory, one must be specified.
+  The solution file to use. The command searches the current directory for one if it's left unspecified, failing if there are multiple solution files.


Suggested change

The solution file to use. The command searches the current directory for one if it's left unspecified, failing if there are multiple solution files.

The solution file to use. If the argument is omitted, the command searches the current directory. If it finds no solution file or multiple solution files, the command fails.

tdykstra · 2020-02-20T16:42:26Z

docs/core/tools/dotnet-sln.md

+
+- **`SOLUTION_FILE`**
+
+  The solution file to use. The command searches the current directory for one if it's left unspecified, failing if there are multiple solution files.


In the H4 Arguments sections I would omit the description for SOLUTION_FILE since that's covered at the top in the H2 Arguments section. If we keep the H4 descriptions we should make sure they're all the same.

I'd prefer to keep them, since I can easily imagine people skipping down to what they think is relevant, then getting confused. I made this one match the one above, though.

tdykstra · 2020-02-20T16:50:49Z

docs/core/tools/dotnet-sln.md

-  Prints out a short help for the command.
-
-### `list`
+  Prints out configurable options for the command.


I vote for "Prints out a description of how to use the command." Whatever we end up with here we can propagate to the other CLI docs later.

Co-Authored-By: Tom Dykstra <[email protected]>

Update dotnet sln

81cec63

Change order and some wording and add an example.

Forgind requested a review from mairaw as a code owner November 5, 2019 00:33

dotnet-bot added this to the November 2019 milestone Nov 5, 2019

dotnet-bot added 📚 Area - .NET Core Guide labels Nov 5, 2019

Forgind requested a review from dsplaisted November 5, 2019 17:07

dsplaisted reviewed Nov 5, 2019

View reviewed changes

Forgind added 2 commits November 5, 2019 10:17

Some feedback

469c66c

Incorporated Rainer's comment

8deacfa

On standard syntax

mairaw assigned Forgind Nov 7, 2019

mairaw previously requested changes Nov 7, 2019

View reviewed changes

Merge branch 'master' into dotnet-sln-docs-update

f615c85

Incorporated some comments

cbbc96a

tdykstra mentioned this pull request Feb 19, 2020

Update dotnet run for 3.0/3.1 #15657

Merged

Merge branch 'master' into dotnet-sln-docs-update

769c8a0

mairaw requested a review from tdykstra as a code owner February 20, 2020 00:46

tdykstra approved these changes Feb 20, 2020

View reviewed changes

Forgind and others added 3 commits February 20, 2020 10:36

Update docs/core/tools/dotnet-sln.md

bd36309

Co-Authored-By: Tom Dykstra <[email protected]>

Update for comments

194b56e

Deleted two spaces that made the linter unhappy

5178b49

tdykstra merged commit 811b1e2 into master Feb 20, 2020

tdykstra deleted the dotnet-sln-docs-update branch February 20, 2020 18:57

tdykstra mentioned this pull request Mar 9, 2020

Add arguments in synopsis sections of CLI ref pages #17398

Closed

BillWagner added dotnet-core/prod cli/subsvc and removed 📚 Area - .NET Core Guide labels Feb 10, 2021

	dotnet sln [<SOLUTION_FILE>] add [--in-root] [-s\|--solution-folder <SOLUTION_FOLDER>] <PROJECT_PATH> [<PROJECT_PATH>...]
	dotnet sln [<SOLUTION_FILE>] add [--in-root] [-s\|--solution-folder] <PROJECT_PATH> [<PROJECT_PATH>...]

	The solution file to use. The command searches the current directory for one if it's left unspecified, failing if there are multiple solution files.
	The solution file to use. If the argument is omitted, the command searches the current directory. If it finds no solution file or multiple solution files, the command fails.


		- `SOLUTION_FILE`

		The solution file to use. The command searches the current directory for one if it's left unspecified, failing if there are multiple solution files.

Update dotnet sln #15694

Update dotnet sln #15694

Uh oh!

Conversation

Forgind commented Nov 5, 2019 • edited by mairaw Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dsplaisted left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mairaw left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mairaw commented Nov 7, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Forgind commented Nov 7, 2019

Uh oh!

mairaw commented Nov 10, 2019

Uh oh!

Forgind commented Nov 12, 2019

Uh oh!

dsplaisted commented Nov 12, 2019

Uh oh!

mairaw commented Jan 14, 2020

Uh oh!

mairaw commented Feb 20, 2020

Uh oh!

tdykstra left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Forgind commented Nov 5, 2019 •

edited by mairaw

Loading

mairaw commented Nov 7, 2019 •

edited

Loading